Skip to content

feat(cliproxy): 补齐 CLIProxyAPI 管理页面 10 项功能#199

Merged
g1331 merged 9 commits into
masterfrom
feat/enhance-cliproxy-management
May 31, 2026
Merged

feat(cliproxy): 补齐 CLIProxyAPI 管理页面 10 项功能#199
g1331 merged 9 commits into
masterfrom
feat/enhance-cliproxy-management

Conversation

@g1331

@g1331 g1331 commented May 31, 2026

Copy link
Copy Markdown
Owner

Summary

参照 CLIProxyAPI 原生 WebUI (Management Center) 的能力覆盖范围,为 AutoRouter 管理端补齐 10 项 CLIProxyAPI 管理能力。改动横跨管理 API 客户端、服务层、Admin 路由、前端 hooks、UI 组件与国际化六层,并提供完整的单元/组件测试覆盖。

Related OpenSpec change

openspec/changes/enhance-cliproxy-management/(proposal + design + 5 个 spec + tasks,全部 artifact 已完成)

Type of Change

  • New feature (non-breaking change that adds functionality)

Changes

后端

  • 管理 API 客户端(src/lib/services/cliproxy-management-client.ts)
    • 新增 `deleteAuthFile` / `uploadAuthFile` / `downloadAuthFile` / `submitOAuthCallback` / `getLogs` 5 个方法
    • `CLIPROXY_OAUTH_PROVIDERS` 从 3 个扩展到 6 个:codex / anthropic / gemini / xai / antigravity / kimi
    • `requestManagementApi` 新增 `returnRawText` 选项以支持下载端点的纯文本响应
  • 服务层
    • cliproxy-auth-account-service 新增 `deleteCliproxyAuthAccount` / `uploadCliproxyAuthFile` / `downloadCliproxyAuthFile` / `listCliproxyAccountModels`
    • cliproxy-oauth-login-service 新增 `submitCliproxyOAuthCallback`
    • 新增独立服务 cliproxy-instance-logs-service 与 cliproxy-linked-upstreams-service
  • Admin 路由(src/app/api/admin/cliproxy/instances/[id]/)
    • POST /auth-files、GET/DELETE /auth-files/[name]
    • POST /oauth-callback
    • GET /logs(支持 since 时间戳)
    • GET /linked-upstreams
    • GET /auth-accounts/[accountName]/models

前端

  • 新增 6 个组件:账号模型对话框、账号详情对话框、认证文件上传对话框、删除认证文件对话框、关联上游面板、实例日志面板
  • 修改 5 个组件:实例表格(行内 Switch 启停)、账号表格(邮箱列 + 4 个新操作)、账号面板(上传入口)、OAuth 登录弹窗(6 个 Provider + 手动回调提交)、主页(挂载日志与关联上游面板)
  • hooks:新增 8 个 hooks 覆盖关联上游、模型查询、日志、启停切换、上传、删除、下载、OAuth 回调
  • i18n:en.json 与 zh-CN.json 同步新增 70+ 条文案

设计权衡

  • xAI / Antigravity / Kimi 仅参与 OAuth 登录,不参与池上游创建(CLIProxyAPI 侧的路径后缀与路由能力约定尚未稳定)。引入 `CliproxyUpstreamProvider` 子集类型严格约束池上游 hook 与表单选项。
  • 下载端点通过 `returnRawText` 复用统一鉴权/超时/错误分类路径,避免独立 fetch 重复模板代码。
  • 日志面板采用手动刷新 + 前端关键词过滤,未引入 SSE。

Test plan

  • `pnpm exec tsc --noEmit` 通过
  • `pnpm lint` 通过
  • cliproxy 测试集 27 文件 214 例全部通过:
    • 服务层 8 文件 96 例
    • admin 路由 8 文件 64 例
    • 组件 10 文件 37 例
    • hooks 1 文件 17 例
  • 浏览器端手动验证全部新增功能的完整交互流程

Checklist

  • 代码遵循项目编码规范
  • 已为相关行为编写测试
  • 涉及破坏性操作(认证文件删除)已通过确认弹窗加防误操作
  • 提交信息遵循 Conventional Commits 约定
  • OpenSpec 变更文档(proposal/design/specs/tasks)齐全

Reviewer notes

  • 提交按阶段拆分,可按提交顺序 review:管理 API 客户端 → 服务层 → 路由 → hooks/i18n → UI
  • 设计文档(openspec/changes/enhance-cliproxy-management/design.md)包含页面布局示意图与所有关键技术决策的备选方案分析

g1331 added 6 commits May 31, 2026 15:35
参照 CLIProxyAPI 原生 WebUI(Management Center)功能覆盖范围,
为 AutoRouter 管理端补齐 10 项 CLIProxyAPI 管理能力:

- 账号模型列表查看、账号详情查看、关联上游面板、实例行内启停切换
- 认证文件上传、下载、删除
- OAuth 回调 URL 手动提交、CLIProxyAPI 实例日志查看
- OAuth Provider 从 3 个扩展到 6 个(新增 xAI/Antigravity/Kimi)

包含 proposal、design、5 个 spec 文件、tasks 共 4 类 artifact,
任务分解为 11 阶段、33 个可验收任务。
- 新增 deleteAuthFile / uploadAuthFile / downloadAuthFile 三个方法,
  覆盖认证文件的删除、上传、下载完整生命周期
- 新增 submitOAuthCallback 方法,支持自动回调不可达时手动提交回调 URL
- 新增 getLogs 方法,支持可选 since 参数与 [] / {logs:[]} 两种上游格式
- CLIPROXY_OAUTH_PROVIDERS 扩展 xai / antigravity / kimi 三个服务商
- requestManagementApi 增加 returnRawText 选项,统一覆盖 download 端点的纯文本响应

为避免类型层强制要求所有 OAuth Provider 都提供池上游 preset,
新增 CliproxyUpstreamProvider 子集类型,池上游 hook 与表单收紧到该子集,
xAI / Antigravity / Kimi 仅参与 OAuth 登录,不参与池上游创建。

测试覆盖:cliproxy-management-client 测试集从 13 例扩展到 33 例,
全部 cliproxy 相关单元/组件测试 116 例通过。
- cliproxy-auth-account-service 新增 deleteCliproxyAuthAccount、
  uploadCliproxyAuthFile、downloadCliproxyAuthFile、listCliproxyAccountModels
  四个服务方法,分别处理删除(先上游再缓存)、上传后立即同步、
  原始 JSON 下载、只读模型列表查询
- cliproxy-oauth-login-service 新增 submitCliproxyOAuthCallback,
  支持自动回调不可达时由管理员手动粘贴回调 URL,提交成功后自动同步账号
- 新增独立 cliproxy-instance-logs-service,通过 getLogs 拉取实例运行日志,
  支持可选 since 时间戳过滤
- 新增独立 cliproxy-linked-upstreams-service,按 cliproxyInstanceId 查询
  关联上游,按是否绑定 authFileName 区分池上游与单账号上游两种类型

测试覆盖:新增 14 个单元测试,cliproxy 服务测试集累计 96 例通过。
- POST /instances/:id/auth-files —— 上传认证文件,触发同步后返回结果
- GET / DELETE /instances/:id/auth-files/:name —— 下载与删除认证文件
- POST /instances/:id/oauth-callback —— 手动提交 OAuth 回调 URL
- GET /instances/:id/logs?since= —— 拉取实例日志
- GET /instances/:id/linked-upstreams —— 列出实例下的关联上游
- GET /instances/:id/auth-accounts/:accountName/models —— 查询账号模型列表

下载端点单独处理响应头(application/json + Content-Disposition),
其他端点统一走 handleCliproxyRouteError,覆盖 401/400/404/502 分类映射。
所有账号文件名参数经 decodeURIComponent 解码后再传入服务层。

测试覆盖:5 个新测试文件共 23 个测试,cliproxy admin 测试集累计 64 例通过。
同步加入 .claude/scheduled_tasks.lock 到 .gitignore 并清理误提交记录。
hooks(src/hooks/use-cliproxy.ts)新增:
- useCliproxyLinkedUpstreams / useCliproxyAccountModels / useCliproxyInstanceLogs
  三个 query hook,分别查询关联上游、账号模型、实例日志
- useToggleCliproxyInstanceEnabled —— 实例行内启停切换
- useUploadCliproxyAuthFile / useDeleteCliproxyAuthFile —— 上传与删除认证文件
- useDownloadCliproxyAuthFile —— 通过 Blob + a[download] 触发浏览器原生下载
- useSubmitCliproxyOAuthCallback —— 手动提交 OAuth 回调 URL

i18n:en.json 与 zh-CN.json 同步新增 70+ 条文案,覆盖三个新 Provider 名称、
认证文件上传/下载/删除、日志面板、关联上游面板、账号详情、账号模型、
OAuth 手动回调等全部新增 UI 文案。
新增组件:
- cliproxy-account-models-dialog —— 查看账号在 CLIProxyAPI 侧的可用模型列表
- cliproxy-account-detail-dialog —— 展示账号完整元数据(邮箱、状态、原始快照、时间戳等)
- cliproxy-auth-file-upload-dialog —— 选择文件或粘贴 JSON 两种方式上传认证文件
- cliproxy-delete-auth-file-dialog —— 删除认证文件的确认弹窗
- cliproxy-linked-upstreams-panel —— 展示实例下的关联池上游与单账号上游
- cliproxy-instance-logs-panel —— 实例日志查看,支持刷新、关键词过滤、日志级别配色

修改组件:
- cliproxy-instances-table —— 状态列改为 Switch,行内启停切换实例
- cliproxy-accounts-table —— 新增邮箱列,模型数可点击查看模型列表,
  操作菜单新增详情/模型/下载/删除四项
- cliproxy-accounts-panel —— 新增上传按钮并整合详情、模型、删除三个弹窗
- cliproxy-oauth-login-dialog —— Provider 选择器自动覆盖 6 个 OAuth 提供方,
  失败状态额外提供手动回调 URL 提交入口
- system/cliproxy/page.tsx —— 选中实例后同时显示账号、关联上游、日志三个面板

测试覆盖:5 个新组件测试 17 个用例,cliproxy 测试集 27 文件 214 例全部通过。
最终 tsc / lint / 全量 cliproxy 测试均通过。
@codecov

codecov Bot commented May 31, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 76.11465% with 75 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.41%. Comparing base (c76427f) to head (349d52b).
⚠️ Report is 1 commits behind head on master.
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@            Coverage Diff             @@
##           master     #199      +/-   ##
==========================================
+ Coverage   74.04%   74.41%   +0.36%     
==========================================
  Files         152      160       +8     
  Lines       11301    11595     +294     
  Branches     3892     3965      +73     
==========================================
+ Hits         8368     8628     +260     
- Misses       1721     1727       +6     
- Partials     1212     1240      +28     
Flag Coverage Δ
verify 74.41% <76.11%> (+0.36%) ⬆️
🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

g1331 added 3 commits May 31, 2026 16:56
按 PR 自评清单逐项处理:

- 实例表 Switch 由全表禁用收窄为行级判定(toggleEnabled.variables.id),消除单行切换期间整张表卡死的问题
- useDownloadCliproxyAuthFile 将 revokeObjectURL 推迟到下一个事件循环,修复 Firefox 上 Blob 尚未读取就失效的下载失败
- submitCliproxyOAuthCallback / pollCliproxyOAuthStatus 把 syncCliproxyAuthAccounts 失败降级为告警,授权成功仍返回 ok 并通过 syncError 透出告警
- CliproxyLinkedUpstream.provider 由字符串 "unknown" 兜底改为 string | null,前端按 linkedUpstreamProviderUnknown 文案展示
- 消除 CliproxyLogEntry / CliproxyAuthFileModel / CliproxyLinkedUpstreamKind 跨文件重复定义,统一以 @/types/cliproxy 为单一来源
- 池上游 Provider 列表收敛为 @/types/cliproxy 中的 CLIPROXY_UPSTREAM_PROVIDERS 常量,pool-upstreams route 与 upstream-preset 共享同一来源
- 删除认证文件弹窗改用 Button variant="destructive",与其余 destructive 按钮风格一致
- 下载端点 Content-Disposition 按 RFC 6266 输出(ASCII fallback + filename*),并过滤 CR/LF 与控制字符
- 上传端点新增 512 KiB Content-Length 上限,避免异常请求体绑架进程
- oauth-callback 增加 http(s) 协议白名单,拒绝非预期 scheme
- 抽出 resolveCliproxyManagementTarget helper 复用于 logs-service 与 oauth-login-service,消除 target 构造重复
- 移除一次性常量 LOGS_QUERY_KEY、回调提交成功使用专用 i18n key oauthCallbackSubmitSuccess
- 新增 cliproxy-instances-table 测试,覆盖行级 Switch 禁用与点击冒泡
- 新增 cliproxy-accounts-table 测试,覆盖 7 项菜单操作回调与字段渲染
- 新增 cliproxy-delete-auth-file-dialog 测试,覆盖删除成功 / 失败 / 取消路径
- 新增 cliproxy-accounts-panel 集成测试,覆盖上传 / OAuth / 删除 / 下载 / 启停的状态协调
- 扩展 cliproxy-oauth-login-dialog 测试,覆盖手动回调输入与提交路径
- 扩展 use-cliproxy hooks 测试,新增 useToggleCliproxyInstanceEnabled、useUpload/Delete/SubmitCallback、useLinkedUpstreams、useAccountModels、useInstanceLogs 共 9 项
- 扩展 cliproxy-upstream-preset 测试,新增 xai/antigravity/kimi 三类 OAuth Provider 拒绝路径
- 扩展 cliproxy-oauth-login-service 测试,新增 sync 失败时仍返回 ok 并附带 syncError 的行为
- 对齐 logs-service / oauth-login-service 测试至 resolveCliproxyManagementTarget 重构后的 mock 路径
合并主分支 spec:

- cliproxy-admin-ui: +3 -1
- cliproxy-oauth-account-management: +4 ~2
- 新建 cliproxy-auth-file-operations / cliproxy-instance-logs / cliproxy-oauth-callback 三套 spec
@g1331 g1331 merged commit 4cbec49 into master May 31, 2026
12 checks passed
@g1331 g1331 deleted the feat/enhance-cliproxy-management branch May 31, 2026 12:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant